Sprite Media Handler Functions14

SetSpriteMediaSpriteProperty

The SetSpriteMediaSpriteProperty function sets the specified property of a sprite.



 
pascal ComponentResult SetSpriteMediaSpriteProperty (

                     MediaHandler mh,

                     short spriteIndex,

                     long propertyType,

                     void* propertyValue);

mh: Specifies the sprite media handler for this operation.
spriteIndex: Specifies the index of the sprite to be modified.
propertyType: Specifies the property to be set.
propertyValue: Specifies the new value of the property.

DISCUSSION

You call this function to modify a property of a sprite. You set the propertyType parameter to the property you want to modify. You set the spriteIndex parameter to the index of the sprite whose property you want to set. The index must be between one and the number of available sprites. You can determine how many sprites are available by calling CountSpriteMediaSprites .

The type of data you pass for the propertyValue parameter depends on the property type. The following table lists the sprite properties and the data types of the corresponding property values.

Sprite Property	Data Type
`kSpritePropertyMatrix`	`MatrixRecord *`
`kSpritePropertyVisible`	`short`
`kSpritePropertyLayer`	`short`
`kSpritePropertyGraphicsMode`	`ModifierTrackGraphicsModeRecord *`
`kSpritePropertyImageIndex`	`short`

RESULT Codes

`noErr`	0	No error
`invalidSpritePropertyErr`	-2065	Specified sprite property does not exist
`invalidSpriteIndexErr`	-2067	Sprite index is out of range

GetSpriteMediaSpriteProperty

The GetSpriteMediaSpriteProperty function retrieves the value of the specified sprite property.



 
pascal ComponentResult GetSpriteMediaSpriteProperty (

                     MediaHandler mh,

                     short spriteIndex,

                     long propertyType,

                     void* propertyValue);

mh: Specifies the sprite media handler for this operation.
spriteIndex: Specifies the index of the sprite for this operation.
propertyType: Specifies the property whose value should be retrieved.
propertyValue: On return, contains a pointer to the value of the property.

DISCUSSION

You call this function to retrieve a value of a sprite property. You set the propertyType parameter to the property you want to retrieve. You set the spriteIndex parameter to the index of the sprite whose property you want to retrieve. The index must be between one and the number of available sprites. You can determine how many sprites are available by calling CountSpriteMediaSprites .

On return, the propertyValue parameter contains a pointer to the specified property's value; the data type of that value depends on the property. The following table lists the sprite properties and the data types of the corresponding property values.

Sprite Property	Data Type
`kSpritePropertyMatrix`	`MatrixRecord *`
`kSpritePropertyVisible`	`short *`
`kSpritePropertyLayer`	`short *`
`kSpritePropertyGraphicsMode`	`ModifierTrackGraphicsModeRecord *`
`kSpritePropertyImageIndex`	`short *`

RESULT Codes

`noErr`	0	No error
`invalidSpritePropertyErr`	-2065	Specified sprite property does not exist
`invalidSpriteIndexErr`	-2067	Sprite index is out of range

HitTestSpriteMedia

The HitTestSpriteMedia function determines whether any sprites are at a specified location.



 
pascal ComponentResult HitTestSpriteMedia (

                     MediaHandler mh,

                     long flags,

                     Point loc,

                     short* spriteHitIndex);

mh: Specifies the sprite media handler for this operation.
flags: Specifies flags to control the hit testing operation.
loc: Specifies a point in the coordinate system of the sprite track's movie to test for the existence of a sprite.
spriteHitIndex: Contains a pointer to a short integer. On return, this integer contains the index of the frontmost sprite at the location specified by loc . If no sprite exists at the location, the function sets the value of this parameter to 0.

DISCUSSION

You call this function to determine whether any sprites exist at a specified location in the coordinate system of a sprite track's movie. You can pass flags to this function to control the hit testing operation more precisely. For example, you may want the hit test operation to detect a sprite whose bounding box contains the specified location. The allowable flags for sprite hit testing are described in "Movie Toolbox: Sprite Toolbox."

CountSpriteMediaSprites

The CountSpriteMediaSprites function retrieves the number of sprites that currently exist in a sprite track.



 
pascal ComponentResult CountSpriteMediaSprites (

                     MediaHandler mh,

                     short* numSprites);

mh: Specifies the sprite media handler for this operation.
numSprites: Contains a pointer to a short integer. On return, this integer contains the number of sprites for the sprite media's current time.

DISCUSSION

This function determines the number of sprites that currently exist based on the key frame that is in effect.

CountSpriteMediaImages

The CountSpriteMediaImages function retrieves the number of images that currently exist in a sprite track.



 
pascal ComponentResult CountSpriteMediaImages (

                     MediaHandler mh,

                     short* numImages);

mh: Specifies the sprite media handler for this operation.
numImages: Contains a pointer to a short integer. On return, this integer contains the number of images for the sprite media's current time.

DISCUSSION

This function determines the number of images that currently exist based on the key frame that is in effect.

GetSpriteMediaIndImageDescription

The GetSpriteMediaIndImageDescription function retrieves an image description for the specified image in a sprite track.



 
pascal ComponentResult GetSpriteMediaIndImageDescription (

                     MediaHandler mh,

                     short imageIndex,

                     ImageDescriptionHandle imageDescription);

mh: Specifies the sprite media handler for this operation.
imageIndex: Specifies the index of the image whose image description should be retrieved.
imageDescription: Specifies an image description handle. On return, this handle contains the image description for the specified image.

DISCUSSION

You set the imageIndex parameter to the index of the image whose image description you want to retrieve. The index must be between one and the number of available images. You can determine how many images are available by calling CountSpriteMediaImages .

The handle specified by the imageDescription parameter must be unlocked; this function resizes the handle if necessary.

RESULT CODES

`noErr`	0	No error
`paramErr`	-50	Invalid parameter specified
`invalidImageIndexErr`	-2068	Image index is out of range

Memory Manager errors, as documented in Inside Macintosh: Memory .

GetDisplayedSampleNumber

The GetDisplayedSampleNumber function retrieves the number of the sample that is currently being displayed.



 
pascal ComponentResult GetDisplayedSampleNumber (

                     MediaHandler mh,

                     long* sampleNum);

mh: Specifies the sprite media handler for this operation.
sampleNum: Contains a pointer to a long integer. On return, this integer contains the number of the sample that is currently being displayed.

DISCUSSION

You call this function when you need to retrieve the sample number of the sample that is being displayed.

SpriteMediaGetURLLink

The QTVideoOutputGetClientName function gets the uniform resource locator (URL) for the currently displayed image for a sprite.



 
pascal ComponentResult SpriteMediaGetURLLink (

                     MediaHandler mh, 

                     short spriteIndex, 

                     Handle *urlLink );

mh: Specifies the sprite media handler for this operation.
spriteIndex: Specifies the index of the sprite.
urlLink: Contains the URL for the sprite, or nil if there is no URL for the sprite.

DISCUSSION

The caller of the QTVideoOutputGetClientName function must dispose of the handle returned by the function.

RESULT CODES

To be provided.